<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>Crunchy Frog VLAM</title>
</head>
<body>
<h1>VLAM summary</h1>
<p>Very Little Aditional Markup is the system used by Crunchy Frog to describe its interactive elements.
 VLAM is essentially just an extended set of attributes for some common HTML tags. Any .htm or .html file loaded through Crunchy Frog
 will have its VLAM code processed. Here's what it can describe:</p>
<ul>
<li><a href="#interpreter">Interpreter</a></li>
<li><a href="#editor">Code editor</a></li>
<li><a href="#doctest">DocTest</a></li>
<li><a href="#canvas_ref">Graphics: Canvas</a></li>
<li><a href="#plot_ref">Graphics: Plot</a></li>
<li><a href="#crunchy">"Crunchy Only" markup</a></li>
</ul>
<p>A description of these follows the "Crunchy attributes" section.</p>
<p>If you prefer, you can also look at a file with <a href="/docs/crunchy_maker/vlam_examples.html">VLAM examples</a>.</p>

<h1>Crunchy attributes</h1>
<p>The following table is a summary of available "crunchy attributes"; these 
are attributes of the html tag "title".</p>
<table summary="Cruncy attributes" class='summary'>
<tr>
	<td><code>none</code></td>
	<td>Does not insert an interactive element; simply styles the code inside 
	the &lt;pre&gt; element.<br/>
	Can be used with: <code>interpreter, editor, doctest, canvas, plot</code>.
	</td>
</tr>
<tr>
	<td><code>editor</code></td>
	<td>Inserts a &lt;textarea&gt; after the &lt;pre&gt; element.<br/>
	Can be used with: <code>interpreter</code>.</td>
</tr>
<tr>
	<td><code>doctest</code></td>
	<td>Treats the code inside the &lt;pre&gt; element as a python doctest to 
	be executed together with the user-code inside the &lt;textarea&gt;.</td>
</tr>
<tr>
	<td><code>interpreter</code></td>
	<td>Inserts a Python interpreter after the &lt;pre&gt; element, unless the 
	attribute also contains <code>editor</code>.<br/>
	Can be used with: <code>interpreter</code>.</td>
</tr>
<tr>
	<td><code>canvas</code></td>
	<td>Inserts a &lt;canvas&gt; for pixel-based drawing after the &lt;pre&gt; 
	element.</td>
</tr>
<tr>
	<td><code>plot</code></td>
	<td>Inserts a &lt;canvas&gt; used for plotting functions after the 
	&lt;pre&gt; element.</td>
</tr>
<tr>
	<td><code>no-copy</code></td>
	<td>Prevents the Python code inside the &lt;pre&gt; element from being
	copied into the &lt;textarea&gt;.<br/>
	Can be used with: <code>interpreter, editor, canvas, plot</code>.</td>
</tr>
<tr>
	<td><code>linenumber</code></td>
	<td>Inserts line numbers before each code line inside the &lt;pre&gt; 
	element.<br/>
	Can be used with: <code>none, interpreter, editor, doctest, canvas, plot</code>.</td>
</tr>
<tr>
	<td><code>size = (rows, cols)</code></td>
	<td>Set the size of the &lt;textarea&gt;; the default is 10 rows by 80 
	columns. <br/>
	Can be used with: <code>interpreter, editor, doctest, canvas, plot</code>.</td>
</tr>
<tr>
	<td><code>area = (width, height)</code></td>
	<td>Set the size of the drawing &lt;canvas&gt; (canvas or plot); the 
	default is a square region, 400 pixels in size.<br/>
	Can be used with: <code>canvas, plot</code>.</td>
</tr>
<tr>
	<td><code>no-pre</code></td>
	<td><code>no-pre</code> does not show the code inside the &lt;pre&gt; 
	element, only inside the &lt;textarea&gt;.  Since this does not make sense 
	for a doctest nor for an <code>interpreter to editor</code> option, or if 
	<code>no-copy</code> is present, it is ignored in these cases.  A 
	typical use of <code>no-pre</code> is to include a complete (long)
	listing for execution at the end of a tutorial, after the main sections 
	have been explained separately.<br/>
	Can be used with: <code>editor, canvas, plot</code>.</td>
</tr>

<tr>
	<td><code>external</code></td>
	<td><code>external</code> tells Python to spawn a new process, as an external application.<br/>
	Can be used with: <code>editor</code>.</td>
</tr>

<tr>
	<td><code>nointernal</code></td>
	<td><code>nointernal</code>, can be used with <code>external</code> to only allow spawning an application as a separate process.  Sometimes (for example: if a tutorial makes use of a module that may not exist on the user's computer) it is useful to be able to launch a process "internally", so that error messages appear in the browser window.<br/>
	Can be used with: <code>editor</code>.</td>
</tr>

<tr>
	<td><code>console</code></td>
	<td><code>console</code> is used with <code>external</code> to spawn a new 
process using a new console/terminal.  This can be used for launching an 
external Python interpreter.  However, this might not be desired if one wants 
to launch a GUI based app. Note that this option only has an effect for 
programs using Windows (and not *nix).<br/>
	Can be used with: <code>editor</code>.</td>
</tr>

</table>


<h2><a id="interpreter">Interpreter</a></h2>
<p><code>&lt;pre title="interpreter [linenumber]"&gt;&lt;/pre&gt;</code> adds 
a Python  interpreter to a page. Any number of interpreter "prompts" can 
appear within a page, and every interpreter prompt used in a given session 
shares the same environment.  
This means that, if you need to import a given module as you go
through a tutorial, you only have to do it once.</p>
<p>Any text between the <code>pre</code> tags is placed before the interpreter, in a <code>pre</code> element. If the <code>linenumber</code>
option is present, a line number will appear before each line of input
code.</p>
<p>Interpreters use the following CSS classes:</p>
<dl>
<dt>#output pre</dt>
	<dd>The output.</dd>
<dt>#output pre.stdin</dt>
	<dd>Input echoed back to the page.</dd>
<dt>#input</dt>
	<dd>The textbox used for input</dd>
<dt>#tipbar</dt>
	<dd>The 'popup' box.</dd>
</dl>
<h2><a id="editor">Code Editor</a></h2>
<p>Code in a code editor is saved in a temporary file and executed as a module in a separate process.</p>
<p><code>&lt;pre title="editor [size=(rows, cols)] [no-copy] [linenumber]"&gt;<br/>
<span class="py_keyword">print</span> "Hello world!"
<br/>
&lt;/pre&gt;</code><br/>
adds a code editor (html &lt;textarea&gt;) to the current page.
The <code>size</code> and <code>no-copy</code> bits are <b>optional</b>.</p>
<p><code>size</code> describes the size of the textarea in characters 
(height, width); if its not present thse textarea
defaults to 10 by 80 characters</p>
<p>By default, Crunchy copies the contents of the <code>pre</code> into a new 
<code>pre</code> above the editor; however, this is prevented if 
<code>no-copy</code> is present. 
If the <code>linenumber</code>
option is present, a line number will appear before each line of input
code.</p>
<p>Any text between the <code>pre</code> tags is placed before the editor, in a <code>pre</code> element to serve as a constant reference for the user.</p>
<p>Code Editors use the following CSS classes:</p>
<dl>
<dt>span.stdout</dt>
	<dd>Output from stdout (ie. normal output).</dd>
<dt>span.stderr</dt>
	<dd>Output from stderr (ie. error output).</dd>
<dt>div.term_out</dt>
	<dd>The div containing all the output.</dd>
</dl>

<h2><a id="interpreter2">Interpreter to code editor</a></h2>
<p>Quite often, Python tutorials are written with simulated sessions
using the interpreter. When the examples are fairly short, this is a 
convenient thing to do.  Sometimes however, the examples given are fairly 
long.  To save on typing, an option is available to take a "fake interpreter 
session" reproduced within a Python tutorial and embed the code (stripped of 
the Python prompts) within an editor.  The required markup to do so is (note 
that the <code>[to]</code> has no effect other than making the intent clearer for the human reader):</p>
<pre>&lt;pre title="interpreter [to] editor size=(h, w) [no-copy] [linenumber]"&gt;
&gt;&gt;&gt; <span class="py_keyword">for</span> i <span class="py_keyword">in</span> range(3):
...     <span class="py_keyword">print</span> "Hello world!"
... 
"Hello world!"
"Hello world!"
"Hello world!"
&lt;/pre&gt;
</pre>
<p>This option will create an editor box and, unless <code>no-copy</code> is present, copy lines of code beginning with either <code>&gt;&gt;&gt; </code> or <code>... </code> (but stripping the prompt), while skipping lines without the prompt. For the above example, the code included in the editor will be:</p>
<pre>
<span class="py_keyword">for</span> i <span class="py_keyword">in</span> range(3):
    <span class="py_keyword">print</span> "Hello world!"
</pre>
<h2><a id="doctest">DocTest</a></h2>
<p><code>&lt;pre title="editor [size=(rows, cols)]  
[linenumber]"&gt;&lt;/pre&gt;</code> adds a doctest to the page; the text 
between the <code>pre</code> tags is always placed before the textarea and 
used as the doctest.</p>
<p>Code entered into a doctest textarea is treated as follows upon execution:</p>
<ol>
	<li>The doctest is prepended.</li>
	<li>The code: <br/>
<pre><span class="py_keyword">import</span> doctest <span class="py_keyword">as</span> __doctest
<span class="py_keyword">if</span> __doctest.testmod()[0] == 0:
    <span class="py_keyword">print</span> "Congratulations!"</pre>Is appended.</li>
	<li>The code is executed in the same way as code from an editor textarea.</li>
</ol>
<p>Note that the semantics for doctests are identical to code editors except that the <code>no-copy</code> part has no 
meaning.</p>
<p>Doctests use the following CSS classes:</p>
<dl>
<dt>span.stdout</dt>
	<dd>Output from stdout (ie. normal output).</dd>
<dt>span.stderr</dt>
	<dd>Output from stderr (ie. error output).</dd>
<dt>div.doctest_out</dt>
	<dd>The div containing all the output.</dd>
</dl>


<h2><a id="canvas_ref">Graphics: Canvas</a></h2>
<p><code>&lt;pre title="canvas [size=(rows, cols)] [no-copy] [linenumber] [area=(width, height)] "&gt;<br/>
Optional Python code here<br/>
&lt;/pre&gt;<br/>
</code>
creates an html &lt;canvas&gt; together with a textarea similar to that of an editor. 
Unless <code>no-copy</code> is present, the code entered in the &lt;pre&gt; 
area is copied into the textarea. If the <code>linenumber</code>
option is present, a line number will appear before each line of input
code. Note that the code executed does not yield any printed output; only a 
drawing is created. The <code>area</code> specifies the size of the drawing area.</p>
<p>IMPORTANT: the &lt;canvas&gt; element is only supported natively in 
Firefox 1.5+, Opera and Safari, but not Internet Explorer.  
Crunchy Frog (0.6) has been tested with Firefox 1.5+ (it works), Opera (it 
mostly works) and Internet Explorer (it does not work), but it has not been 
tested with Safari or other browsers.</p>


<h2><a id="plot_ref">Graphics: Plot</a></h2>
<p>Whereas <code>canvas</code> creates a pixel based drawing area, </p>
<p><code>&lt;pre title="plot [size=(rows, cols)] [no-copy] [linenumber] [area=(width, height)] "&gt;<br/>
Optional Python code here<br/>
&lt;/pre&gt;<br/>
</code>
creates a "plotting canvas", designed to plot function (within a certain 
range, both in the <em>x</em> and the <em>y</em> direction); otherwise,
the syntax is the same as for the graphics canvas.</p>

<h2><a id="crunchy">"Crunchy only" markup</a></h2>
<p>Crunchy Frog will automatically colourize the Python code between the <code>&lt;pre title="..."&gt; ...&lt;/pre&gt;</code> tags, provided that
the "title" attribute contains a valid Python interactive element name 
(interpreter, doctest, editor, canvas).  Sometimes, you may want simply to 
colourize the Python code without actually inserting an interactive element.  You can do so by writing:</p>
<pre>
&lt;pre title="none [linenumber]"&gt;
...
&lt;/pre&gt;
</pre>
<p>for editor and canvas, and:</p>
<pre>
&lt;pre title="none object [linenumber]"&gt;
...
&lt;/pre&gt;
</pre>
<p>with object replaced by one of "doctest" or "interpreter" (the two are
equivalent) if the code represents an interactive session at the Python
interpreter (which is what doctests are).
</p>
<p>The Python code is styled according to the following classes:</p>
<dl>
<dt>span.py_keyword</dt>
<dt>span.py_number</dt>
<dt>span.py_comment</dt>
<dt>span.py_string</dt>
<dt>span.py_variable</dt>
<dt>span.py_op</dt>
<dt>span.py_linenumber</dt>
<dt>span.py_prompt</dt>
<dt>span.py_output</dt>
</dl>

<p>Comments, normally hidden when viewing the page directly by a browser, but revealed when viewed using Crunchy Frog can be created as follows:<br/><br/>
<code>&lt;span class="vlam_comment" style="display: none"&gt;</code>
<br/>
<em>This sentence is normally hidden but will be revealed by Crunchy Frog.</em><br />
<code>&lt;/span&gt;</code>
<br/><br/>
<p>Comments use the following CSS class:</p>
<dl>
<dt>p.crunchy_comment</dt>
</dl>

<p>"File browser" for loading local tutorials can be inserted with the following code:<br/>
<code>&lt;span title="local_tutorial"&gt; &lt;/span&gt;</code>
</p>

<p>"Form input" for loading remote tutorials can be inserted with the following code:<br/>
<code>&lt;span title="remote_tutorial"&gt;</code> <em>Optional suggested URL goes here</em> <code>&lt;/span&gt;</code>
</p>



</body>
</html>

